---
sidebar_position: 1
title: Firebase introduction
sidebar_label: Introduction
---

Hyper Fetch `firebase` packages offer complete integration of `realtime database` and `firestore`, both for frontend and
backend, with a single, unified approach for all of them.

## Getting Started

In order to start using the firebase adapter, you have to initialize the firestore/realtime database and set the correct
adapter on the `client`.

There are two packages to chose from with two adapters each:

1. `@hyper-fetch/firebase` - for working with web realtime and firestore databases:
   1. `firebaseAdapter` - for standard REST requests.
   2. `firebaseSocketsAdapter` - for realtime listening.
2. `@hyper-fetch/firebase-admin` - for admin versions of the packages:
   1. `firebaseAdminAdapter` - for standard REST requests.
   2. `firebaseSocketsAdminAdapter` - for realtime listening.

Both packages have the same unified interface.

```tsx
import { firebaseAdapter } from "@hyper-fetch/firebase";
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

// Firebase firestore database initialization
const app = initializeApp({
  projectId: "demo-test-firestore",
});
const db = getFirestore(app);

// Setting up the HyperFetch with a firebase adapter
const client = new Client({ url: "teas/" }).setAdapter(() => firebaseAdapter(db));
const getReq = client.createRequest<Tea[]>()({
  endpoint: "",
  method: "getDocs",
});

// Checking the results
const { data, status, extra, success, error } = await getReq.send();
```

In case of firebase admin, the only difference is the import:

```tsx
import { firebaseAdminAdapter } from "@hyper-fetch/firebase-admin";
...
```

Resulting `response` is an object that contains the following properties:

1. `data` - data returned from the database. Each object returned from the database is enhanced also by the `__key`
   param that equals id of a given document.
2. `status` - status indicating whether a request ended with `success`, `error` or `emptyResource`. `emptyResource`
   occurs when the request to firebase succeeded but no data was returned.
3. `success` - general information if overall request succeeded (`true`) or failed (`false`)
4. `error` - contains error object if the request failed.
5. `extra` - contains additional properties, depending on a method used. For instance, for `getDocs` method - it allows
   to access `ref` and `snapshot` from firestore firebase.

## Differences from 'raw' firebase

1. If we store an array in firebase, for instance `[a, b, c]`, the query would return the same array. However, if the
   array stops being sequential - for instance, if `a` and `b` were deleted, firebase would return and object:
   `{2: 'c', 4: 'e'}`. Hyper Fetch always returns and array. Each object in an array has an additional `__key` property,
   that indicates the id of a given object.

## Filtering queries

In order to standardize the interface across both admin/web firestore/realtime, the filtering and limiting queries is
done via setting the `constraints` queryParam:

```tsx
import { $limit, $orderBy, $where } from "constraints";

const req = client.createRequest<Tea[]>()({
  endpoint: "",
  method: "getDocs",
}); // or via setQueryParams method
const { data } = await req.send({
  queryParams: { constraints: [$where("type", "==", "Green"), $orderBy("year"), $limit(1)] },
});
```

User can pass the array of constrains and filters. Please pay attention to the fact that you need to filter via method
wrappers provided via `adapter-firebase` package: `$where`, `$orderBy`, `$limit`, `$startAt`, `$startAfter`, `$endAt`,
`$endAfter`, `$orderByChild`, `$orderByKey`, `$orderByValue`, `$limitToFirst`, `$limitToLast`, `$equalTo`. All of these
methods work exactly the same as their corresponding firebase equivalents.
